<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
<!-- qopengltextureblitter.cpp -->
  <title>QOpenGLTextureBlitter Class | Qt GUI 5.14.2</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="../qtdoc/index.html">Qt 5.14</a></td><td ><a href="qtgui-index.html">Qt GUI</a></td><td ><a href="qtgui-module.html">C++ Classes</a></td><td >QOpenGLTextureBlitter</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtgui-index.html">Qt 5.14.2 Reference Documentation</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-types">Public Types</a></li>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#static-public-members">Static Public Members</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QOpenGLTextureBlitter Class</h1>
<!-- $$$QOpenGLTextureBlitter-brief -->
<p>The QOpenGLTextureBlitter class provides a convenient way to draw textured quads via OpenGL. <a href="#details">More...</a></p>
<!-- @@@QOpenGLTextureBlitter -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign">   <span class="preprocessor">#include &lt;QOpenGLTextureBlitter&gt;</span>
</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += gui</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 5.8</td></tr></table></div><p>This class was introduced in Qt 5.8.</p>
<ul>
<li><a href="qopengltextureblitter-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-types"></a>
<h2 id="public-types">Public Types</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#Origin-enum">Origin</a></b> { OriginBottomLeft, OriginTopLeft }</td></tr>
</table></div>
<a name="public-functions"></a>
<h2 id="public-functions">Public Functions</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#QOpenGLTextureBlitter">QOpenGLTextureBlitter</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#dtor.QOpenGLTextureBlitter">~QOpenGLTextureBlitter</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#bind">bind</a></b>(GLenum <i>target</i> = GL_TEXTURE_2D)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#blit">blit</a></b>(GLuint <i>texture</i>, const QMatrix4x4 &amp;<i>targetTransform</i>, QOpenGLTextureBlitter::Origin <i>sourceOrigin</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#blit-1">blit</a></b>(GLuint <i>texture</i>, const QMatrix4x4 &amp;<i>targetTransform</i>, const QMatrix3x3 &amp;<i>sourceTransform</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#create">create</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#destroy">destroy</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#isCreated">isCreated</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#release">release</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#setOpacity">setOpacity</a></b>(float <i>opacity</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#setRedBlueSwizzle">setRedBlueSwizzle</a></b>(bool <i>swizzle</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#supportsExternalOESTarget">supportsExternalOESTarget</a></b>() const</td></tr>
</table></div>
<a name="static-public-members"></a>
<h2 id="static-public-members">Static Public Members</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> QMatrix3x3 </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#sourceTransform">sourceTransform</a></b>(const QRectF &amp;<i>subTexture</i>, const QSize &amp;<i>textureSize</i>, QOpenGLTextureBlitter::Origin <i>origin</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QMatrix4x4 </td><td class="memItemRight bottomAlign"><b><a href="qopengltextureblitter.html#targetTransform">targetTransform</a></b>(const QRectF &amp;<i>target</i>, const QRect &amp;<i>viewport</i>)</td></tr>
</table></div>
<a name="details"></a>
<!-- $$$QOpenGLTextureBlitter-description -->
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p>Drawing textured quads, in order to get the contents of a texture onto the screen, is a common operation when developing 2D user interfaces. QOpenGLTextureBlitter provides a convenience class to avoid repeating vertex data, shader sources, buffer and program management and matrix calculations.</p>
<p>For example, a <a href="../qtwidgets/qopenglwidget.html">QOpenGLWidget</a> subclass can do the following to draw the contents rendered into a framebuffer at the pixel position <code>(x, y)</code>:</p>
<pre class="cpp">

  <span class="type">void</span> OpenGLWidget<span class="operator">::</span>initializeGL()
  {
      m_blitter<span class="operator">.</span>create();
      m_fbo <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qopenglframebufferobject.html">QOpenGLFramebufferObject</a></span>(size);
  }

  <span class="type">void</span> OpenGLWidget<span class="operator">::</span>paintGL()
  {
      m_fbo<span class="operator">-</span><span class="operator">&gt;</span>bind();
      <span class="comment">// update offscreen content</span>
      m_fbo<span class="operator">-</span><span class="operator">&gt;</span>release();

      m_blitter<span class="operator">.</span>bind();
      <span class="keyword">const</span> <span class="type"><a href="../qtcore/qrect.html">QRect</a></span> targetRect(<span class="type"><a href="../qtcore/qpoint.html">QPoint</a></span>(x<span class="operator">,</span> y)<span class="operator">,</span> m_fbo<span class="operator">-</span><span class="operator">&gt;</span>size());
      <span class="keyword">const</span> QMatrix4x4 target <span class="operator">=</span> <span class="type"><a href="qopengltextureblitter.html#QOpenGLTextureBlitter">QOpenGLTextureBlitter</a></span><span class="operator">::</span>targetTransform(targetRect<span class="operator">,</span> <span class="type"><a href="../qtcore/qrect.html">QRect</a></span>(<span class="type"><a href="../qtcore/qpoint.html">QPoint</a></span>(<span class="number">0</span><span class="operator">,</span> <span class="number">0</span>)<span class="operator">,</span> m_fbo<span class="operator">-</span><span class="operator">&gt;</span>size()));
      m_blitter<span class="operator">.</span>blit(m_fbo<span class="operator">-</span><span class="operator">&gt;</span>texture()<span class="operator">,</span> target<span class="operator">,</span> <span class="type"><a href="qopengltextureblitter.html#QOpenGLTextureBlitter">QOpenGLTextureBlitter</a></span><span class="operator">::</span>OriginBottomLeft);
      m_blitter<span class="operator">.</span>release();
  }

</pre>
<p>The blitter implements GLSL shaders both for GLSL 1.00 (suitable for OpenGL (ES) 2.x and compatibility profiles of newer OpenGL versions) and version 150 (suitable for core profile contexts with OpenGL 3.2 and newer).</p>
</div>
<!-- @@@QOpenGLTextureBlitter -->
<div class="types">
<h2>Member Type Documentation</h2>
<!-- $$$Origin$$$OriginBottomLeft$$$OriginTopLeft -->
<h3 class="fn" id="Origin-enum"><a name="Origin-enum"></a>enum QOpenGLTextureBlitter::<span class="name">Origin</span></h3>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QOpenGLTextureBlitter::OriginBottomLeft</code></td><td class="topAlign tblval"><code>0</code></td><td class="topAlign">Indicates that the data in the texture follows the OpenGL convention of coordinate systems, meaning Y is running from bottom to top.</td></tr>
<tr><td class="topAlign"><code>QOpenGLTextureBlitter::OriginTopLeft</code></td><td class="topAlign tblval"><code>1</code></td><td class="topAlign">Indicates that the data in the texture has Y running from top to bottom, which is typical with regular, unflipped image data.</td></tr>
</table></div>
<p><b>See also </b><a href="qopengltextureblitter.html#blit">blit</a>().</p>
<!-- @@@Origin -->
</div>
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$QOpenGLTextureBlitter[overload1]$$$QOpenGLTextureBlitter -->
<h3 class="fn" id="QOpenGLTextureBlitter"><a name="QOpenGLTextureBlitter"></a>QOpenGLTextureBlitter::<span class="name">QOpenGLTextureBlitter</span>()</h3>
<p>Constructs a new QOpenGLTextureBlitter instance.</p>
<p><b>Note: </b>no graphics resources are initialized in the constructor. This makes it safe to place plain QOpenGLTextureBlitter members into classes because the actual initialization that depends on the OpenGL context happens only in <a href="qopengltextureblitter.html#create">create</a>().</p><!-- @@@QOpenGLTextureBlitter -->
<!-- $$$~QOpenGLTextureBlitter[overload1]$$$~QOpenGLTextureBlitter -->
<h3 class="fn" id="dtor.QOpenGLTextureBlitter"><a name="dtor.QOpenGLTextureBlitter"></a>QOpenGLTextureBlitter::<span class="name">~QOpenGLTextureBlitter</span>()</h3>
<p>Destructs the instance.</p>
<p><b>Note: </b>When the OpenGL context - or a context sharing resources with it - that was current when calling <a href="qopengltextureblitter.html#create">create</a>() is not current, graphics resources will not be released. Therefore, it is recommended to call <a href="qopengltextureblitter.html#destroy">destroy</a>() manually instead of relying on the destructor to perform OpenGL resource cleanup.</p><!-- @@@~QOpenGLTextureBlitter -->
<!-- $$$bind[overload1]$$$bindGLenum -->
<h3 class="fn" id="bind"><a name="bind"></a><span class="type">void</span> QOpenGLTextureBlitter::<span class="name">bind</span>(<span class="type">GLenum</span> <i>target</i> = GL_TEXTURE_2D)</h3>
<p>Binds the graphics resources used by the blitter. This must be called before calling <a href="qopengltextureblitter.html#blit">blit</a>(). Code modifying the OpenGL state should be avoided between the call to bind() and <a href="qopengltextureblitter.html#blit">blit</a>() because otherwise conflicts may arise.</p>
<p><i>target</i> is the texture target for the source texture and must be either <code>GL_TEXTURE_2D</code> or <code>GL_OES_EGL_image_external</code>.</p>
<p><b>See also </b><a href="qopengltextureblitter.html#release">release</a>() and <a href="qopengltextureblitter.html#blit">blit</a>().</p>
<!-- @@@bind -->
<!-- $$$blit[overload1]$$$blitGLuintconstQMatrix4x4&QOpenGLTextureBlitter::Origin -->
<h3 class="fn" id="blit"><a name="blit"></a><span class="type">void</span> QOpenGLTextureBlitter::<span class="name">blit</span>(<span class="type">GLuint</span> <i>texture</i>, const <span class="type"><a href="qmatrix4x4.html">QMatrix4x4</a></span> &amp;<i>targetTransform</i>, <span class="type"><a href="qopengltextureblitter.html#Origin-enum">QOpenGLTextureBlitter::Origin</a></span> <i>sourceOrigin</i>)</h3>
<p>Performs the blit with the source texture <i>texture</i>.</p>
<p><i>targetTransform</i> specifies the transformation applied. This is usually generated by the <a href="qopengltextureblitter.html#targetTransform">targetTransform</a>() helper function.</p>
<p><i>sourceOrigin</i> specifies if the image data needs flipping. When <i>texture</i> corresponds to a texture attached to an FBO pass <a href="qopengltextureblitter.html#Origin-enum">OriginBottomLeft</a>. On the other hand, when <i>texture</i> is based on unflipped image data, pass <a href="qopengltextureblitter.html#Origin-enum">OriginTopLeft</a>. This is more efficient than using <a href="qimage.html#mirrored">QImage::mirrored</a>().</p>
<p><b>See also </b><a href="qopengltextureblitter.html#targetTransform">targetTransform</a>(), <a href="qopengltextureblitter.html#Origin-enum">Origin</a>, and <a href="qopengltextureblitter.html#bind">bind</a>().</p>
<!-- @@@blit -->
<!-- $$$blit$$$blitGLuintconstQMatrix4x4&constQMatrix3x3& -->
<h3 class="fn" id="blit-1"><a name="blit-1"></a><span class="type">void</span> QOpenGLTextureBlitter::<span class="name">blit</span>(<span class="type">GLuint</span> <i>texture</i>, const <span class="type"><a href="qmatrix4x4.html">QMatrix4x4</a></span> &amp;<i>targetTransform</i>, const <span class="type"><a href="qgenericmatrix.html#QMatrix3x3-typedef">QMatrix3x3</a></span> &amp;<i>sourceTransform</i>)</h3>
<p>Performs the blit with the source texture <i>texture</i>.</p>
<p><i>targetTransform</i> specifies the transformation applied. This is usually generated by the <a href="qopengltextureblitter.html#targetTransform">targetTransform</a>() helper function.</p>
<p><i>sourceTransform</i> specifies the transformation applied to the source. This allows using only a sub-rect of the source texture. This is usually generated by the <a href="qopengltextureblitter.html#sourceTransform">sourceTransform</a>() helper function.</p>
<p><b>See also </b><a href="qopengltextureblitter.html#sourceTransform">sourceTransform</a>(), <a href="qopengltextureblitter.html#targetTransform">targetTransform</a>(), <a href="qopengltextureblitter.html#Origin-enum">Origin</a>, and <a href="qopengltextureblitter.html#bind">bind</a>().</p>
<!-- @@@blit -->
<!-- $$$create[overload1]$$$create -->
<h3 class="fn" id="create"><a name="create"></a><span class="type">bool</span> QOpenGLTextureBlitter::<span class="name">create</span>()</h3>
<p>Initializes the graphics resources used by the blitter.</p>
<p>Returns <code>true</code> if successful, <code>false</code> if there was a failure. Failures can occur when there is no OpenGL context current on the current thread, or when shader compilation fails for some reason.</p>
<p><b>See also </b><a href="qopengltextureblitter.html#isCreated">isCreated</a>() and <a href="qopengltextureblitter.html#destroy">destroy</a>().</p>
<!-- @@@create -->
<!-- $$$destroy[overload1]$$$destroy -->
<h3 class="fn" id="destroy"><a name="destroy"></a><span class="type">void</span> QOpenGLTextureBlitter::<span class="name">destroy</span>()</h3>
<p>Frees all graphics resources held by the blitter. Assumes that the OpenGL context, or another context sharing resources with it, that was current on the thread when invoking <a href="qopengltextureblitter.html#create">create</a>() is current.</p>
<p>The function has no effect when the blitter is not in created state.</p>
<p><b>See also </b><a href="qopengltextureblitter.html#create">create</a>().</p>
<!-- @@@destroy -->
<!-- $$$isCreated[overload1]$$$isCreated -->
<h3 class="fn" id="isCreated"><a name="isCreated"></a><span class="type">bool</span> QOpenGLTextureBlitter::<span class="name">isCreated</span>() const</h3>
<p>Returns <code>true</code> if <a href="qopengltextureblitter.html#create">create</a>() was called and succeeded. <code>false</code> otherwise.</p>
<p><b>See also </b><a href="qopengltextureblitter.html#create">create</a>() and <a href="qopengltextureblitter.html#destroy">destroy</a>().</p>
<!-- @@@isCreated -->
<!-- $$$release[overload1]$$$release -->
<h3 class="fn" id="release"><a name="release"></a><span class="type">void</span> QOpenGLTextureBlitter::<span class="name">release</span>()</h3>
<p>Unbinds the graphics resources used by the blitter.</p>
<p><b>See also </b><a href="qopengltextureblitter.html#bind">bind</a>().</p>
<!-- @@@release -->
<!-- $$$setOpacity[overload1]$$$setOpacityfloat -->
<h3 class="fn" id="setOpacity"><a name="setOpacity"></a><span class="type">void</span> QOpenGLTextureBlitter::<span class="name">setOpacity</span>(<span class="type">float</span> <i>opacity</i>)</h3>
<p>Changes the opacity to <i>opacity</i>. The default opacity is 1.0&#x2e;</p>
<p><b>Note: </b>the blitter does not alter the blend state. It is up to the caller of <a href="qopengltextureblitter.html#blit">blit</a>() to ensure the correct blend settings are active.</p><!-- @@@setOpacity -->
<!-- $$$setRedBlueSwizzle[overload1]$$$setRedBlueSwizzlebool -->
<h3 class="fn" id="setRedBlueSwizzle"><a name="setRedBlueSwizzle"></a><span class="type">void</span> QOpenGLTextureBlitter::<span class="name">setRedBlueSwizzle</span>(<span class="type">bool</span> <i>swizzle</i>)</h3>
<p>Sets whether swizzling is enabled for the red and blue color channels to <i>swizzle</i>. An BGRA to RGBA conversion (occurring in the shader on the GPU, instead of a slow CPU-side transformation) can be useful when the source texture contains data from a <a href="qimage.html">QImage</a> with a format like <a href="qimage.html#Format-enum">QImage::Format_ARGB32</a> which maps to BGRA on little endian systems.</p>
<p>By default the red-blue swizzle is disabled since this is what a texture attached to an framebuffer object or a texture based on a byte ordered <a href="qimage.html">QImage</a> format (like <a href="qimage.html#Format-enum">QImage::Format_RGBA8888</a>) needs.</p>
<!-- @@@setRedBlueSwizzle -->
<!-- $$$sourceTransform[overload1]$$$sourceTransformconstQRectF&constQSize&QOpenGLTextureBlitter::Origin -->
<h3 class="fn" id="sourceTransform"><a name="sourceTransform"></a><code>[static] </code><span class="type"><a href="qgenericmatrix.html#QMatrix3x3-typedef">QMatrix3x3</a></span> QOpenGLTextureBlitter::<span class="name">sourceTransform</span>(const <span class="type"><a href="../qtcore/qrectf.html">QRectF</a></span> &amp;<i>subTexture</i>, const <span class="type"><a href="../qtcore/qsize.html">QSize</a></span> &amp;<i>textureSize</i>, <span class="type"><a href="qopengltextureblitter.html#Origin-enum">QOpenGLTextureBlitter::Origin</a></span> <i>origin</i>)</h3>
<p>Calculates a 3x3 matrix suitable as the input to <a href="qopengltextureblitter.html#blit">blit</a>(). This is used when only a part of the texture is to be used in the blit.</p>
<p><i>subTexture</i> is the desired source rectangle in pixels, <i>textureSize</i> is the full width and height of the texture data. <i>origin</i> specifies the orientation of the image data when it comes to the Y axis.</p>
<p><b>See also </b><a href="qopengltextureblitter.html#blit">blit</a>() and <a href="qopengltextureblitter.html#Origin-enum">Origin</a>.</p>
<!-- @@@sourceTransform -->
<!-- $$$supportsExternalOESTarget[overload1]$$$supportsExternalOESTarget -->
<h3 class="fn" id="supportsExternalOESTarget"><a name="supportsExternalOESTarget"></a><span class="type">bool</span> QOpenGLTextureBlitter::<span class="name">supportsExternalOESTarget</span>() const</h3>
<p>Returns <code>true</code> when <a href="qopengltextureblitter.html#bind">bind</a>() accepts <code>GL_TEXTURE_EXTERNAL_OES</code> as its target argument.</p>
<p><b>See also </b><a href="qopengltextureblitter.html#bind">bind</a>() and <a href="qopengltextureblitter.html#blit">blit</a>().</p>
<!-- @@@supportsExternalOESTarget -->
<!-- $$$targetTransform[overload1]$$$targetTransformconstQRectF&constQRect& -->
<h3 class="fn" id="targetTransform"><a name="targetTransform"></a><code>[static] </code><span class="type"><a href="qmatrix4x4.html">QMatrix4x4</a></span> QOpenGLTextureBlitter::<span class="name">targetTransform</span>(const <span class="type"><a href="../qtcore/qrectf.html">QRectF</a></span> &amp;<i>target</i>, const <span class="type"><a href="../qtcore/qrect.html">QRect</a></span> &amp;<i>viewport</i>)</h3>
<p>Calculates a target transform suitable for <a href="qopengltextureblitter.html#blit">blit</a>().</p>
<p><i>target</i> is the target rectangle in pixels. <i>viewport</i> describes the source dimensions and will in most cases be set to (0, 0, image width, image height).</p>
<p>For unscaled output the size of <i>target</i> and <i>viewport</i> should match.</p>
<p><b>See also </b><a href="qopengltextureblitter.html#blit">blit</a>().</p>
<!-- @@@targetTransform -->
</div>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2020 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br/>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br/>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
